Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/scope/051-075/scopedisk52/tutor/c5

Text File | 1995-03-18 | 23KB | 665 lines

Commands covered are:
RUN
EXECUTE
FAILAT
IF
ELSE
ENDIF
QUIT
SKIP
LAB
QUIT

________________________________________________________________________________

RUN
    causes a command to be performed from the CLI

    This command has virtually the same result as just typing a command
in at the CLI prompt. Consider the two statements below:

COMMAND [PARAMETERS]
RUN COMMAND [PARAMETERS]

Both of these statements will cause the command "COMMAND" to be initiated, the
difference is that by using the RUN command, COMMAND will open it's own CLI
and be performed from that one and it will release control of your CLI for
further input by you...and isn't that what multi-tasking is all about?

    To illustrate this point, we'll use the ED command again, since it's
one that will take over if allowed. We won't be writing anything into the
editor. Just watch your command window's prompt.

>> ED ram:foo

/* After ED has finished loading and has displayed it's screen, you'll notice
that your command window's prompt did not return. You can still type commands
into this window, but they'll have to wait until the window is released by ED
before they can be handled. So what?
    Let's say that you wanted to create a file and have it written to ram:,
but since ED only writes to the current directory and since we didn't "CD ram:"
before we started ED going, your results will not end up where you wanted them.
Typing in "CD ram:" into the window at this point, will simply put your demand
on hold until the window becomes free again. */

    Activate ED and press <ESC>:
*Q

    OK, now type in:

>> RUN ED ram:foo

/* This time your prompt returned to the ready position and you can utilize
this window for any commands you might want to run while still doing your
editing chores. */

        Activate ED and press <ESC>:
*Q

    There are times that you might intentionally want to tie-up the window
and there are commands like DIR that don't tie the window up very long and
automatically return control with no action on your part, so you don't have
to RUN everything, but this decision-making will become more natural with
experience.

    One last thing, RUN is not meant to be used with batchfiles. If you
try to RUN a batchfile, you'll get an error that will tell that the file
is not an object module and give you the number 121. This simply put means
that the file you tried to RUN is not in the proper format (a binary
executable program). EXECUTE is the command you want for batchfiles.

________________________________________________________________________________

EXECUTE

    is used to tell DOS that it is to read a text file of CLI commands
    and follow the commands contained therein.

    Why not just type in the commands you need and not even bother with
batchfiles at all?

    You could. But to make things easier on yourself, you'll make and
use batchfiles to perform operations that require a lot of commands that
get repeated very often.

    Batchfiles are regular, garden variety text files that can be
written, edited, and stored the same way you might write a letter to your
mother. The exception being that each line contains a command exactly the
way it would appear if you had typed it into the CLI at the prompt.

    The "startup-sequence" that configures your Amiga when you put
a WB in at boot-up time is a batchfile.

>> TYPE s:startup-sequence
/* the startup-sequence will appear */

    It doesn't matter if it scrolls off the top of the window, but what's
important is that you have a look at it and see how each line is a unique
command. Hopefully, even though all the commands may not be ones we've
discussed yet, it's apparent that you WOULD get the same results by typing
each line into the CLI seperately.

    This should also illustrate that the Amiga doesn't do anything
magical when you insert the WB at the hand-picture prompt. It will make the
assignments that we looked at in Section 1, looks in the S: directory, and
if it finds a file called "startup-sequence" it EXECUTEs it. /* If there
isn't a "startup-sequence" in S:, it doesn't have anything to do and just stops
with a CLI open */

    The next logical step following the facts that A) the startup-
sequence is a batchfile; and B) batchfiles can be edited /* read customized */;
it follows that you can cause all manner of things to happen when you're
machine starts up.

    One other important fact to note is that you can pass an parameter
to be used within the batchfile from the command line. This is done by using
a special character within the file to signal DOS that a substitution is to
be performed. This character is the period ".".  A stipulation to using these
lines is that if there are ANY within the file, at least THE FIRST LINE MUST
CONTAIN ONE. The most common one that we might use at this level of skill is
the ".KEY" or ".K" option.

    Let's say we want to create a batchfile that will start some program
running. Let's also assume that it requires that the logical name FONTS: is
assigned to it's font directory and that, to make the program run faster,
we want to put one of it's files in ram:. /* Don't type in the following
lines, they're for illustration only */ We could type in:

BS> ASSIGN fonts: DISKNAME:fonts
BS> COPY DISKNAME:filename ram:
BS> [RUN] PROGRAM

    Now we do whatever we wanted to do and close the program. When we
take the disk out the disk's icon will stay on the screen since FONTS: is
still assigned to that disk, and the file we copied to ram: will still be
there. We can always:

BS> ASSIGN fonts: [WB:fonts]
BS> DELETE ram:filename

    But, it's more trouble than it's worth if it's a program that's
used fairly often and we might just forget.

    So, we're back to our batchfile. We want one that will both start
the program and clean-up after we're done. /* There are a few ways to do
this but to illustrate the use of the ".K" option, we'll go with this. To
begin, you'd start ED and type in the following lines:

/********** ILLUSTRATION ONLY **************/


.K switch       /* 1st line */
IF "<switch>" EQ "on"
 ASSIGN fonts: diskname:fonts
 COPY diskname:filename ram:
 [RUN] diskname:program
 QUIT
ENDIF
IF "<switch>" EQ "off"
 ASSIGN fonts: /* WB:fonts */
 DELETE ram:filename
ENDIF

/*******************************************/

    Now all you'd have to do is:

BS> EXECUTE batchfile [on][off]

and the batchfile would check to see if the word you type at the end of the
command line matches any of the occurances of the .KEYword "switch" and if
it finds a match, it will perform that portion of the file. If it doesn't,
it will just get to the end without doing anything.

    We'll come back to this example as we get more involved.

    Since we must walk before we run. Let's have a look at some of
the commands that are solely used within batchfiles and that appear in our
example. Some will be lumped together because that's the way they function
and they'll make more sense that way.


________________________________________________________________________________

FAILAT

    used to change the level at which the execution of a batchfile will
abort when an error is detected or a command fails.

    An AmigaDOS command will usually return a numberic value if it fails for
some reason or another. This value is usually 5, 10, or 20. The FAILAT command
will prevent a batchfile from aborting should a command fail if the failat level
is set higher than the number returned by the command. By default this level is
set to 10 and upon exiting any given batchfile, this level is reset to the
default.

>> FAILAT
Fail limit: 10
>> FAILAT 20
Fail limit: 20

    In a batchfile, the FAILAT command must preceed any situation your
trying to prevent from aborting the execution. Otherwise the batchfile will exit
before it's reached.

________________________________________________________________________________

IF ELSE ENDIF

    control the determination of conditional arguments and the method
    used to contend with the results.

    For every IF there MUST BE a matching ENDIF!

    This tells DOS where the command[s] we want run, as a result of the
conditional, end[s].

        A few generic examples of how these can be used are:

IF [condition]          IF [condition]          IF [condition]
  [command]               [command]               IF [condition]
ENDIF                   ELSE                        [command]
                          [command]               ENDIF
                        ENDIF                     [command]
                                                ENDIF

>> IF ?
NOT/S,WARN/S,ERROR/S,FAIL/S,,EQ/K,EXISTS/K:

    Whew!
    Let's start by eliminating a few of these that might be beyond the
scope of this tutorial.
    Warn, Error, and Fail check for numberic values that are returned as
a result of the checking the conditional. Since most commands return some value
if they fail, you can check for this by using one of these parameters. The one
thing to keep in mind is that with no changes, a command that fails will cause a
batchfile to terminate. Here's where the FAILAT command would come into play.

    For an example, let's say that we want to create a directory from a
batchfile. MAKEDIR will fail if the directory already exists. Here's one way we
can check for this:

----------- Example batchfile only --------------

failat 21 /* this can be any number greater than the fail value, 20 */
makedir disk:directory
if fail
   [condition]
endif
[failat 20] /* this can be reset if you want the batchfile to terminate on the
next error condition */

-------------------------------------------------

    This leaves us with IF by itself and NOT, EQ, EXISTS as additional
conditionals.

    Keep in mind, batchfiles aren't exactly like writing programs in a
real programming language like C or Basic. They run from top to bottom.

    EQ checks for "equality" between the two items on either side
of it. Note that both of these are surrounded by quotes. This tells it that
these are literal. /* char wouldn't match "x" */

        .K char
        IF "<char>" EQ "X"

    EXISTS looks to see if the conditional is there.

        IF EXISTS [condition]

    NOT checks for a negative situation.

        IF NOT [condition]

    Sometimes you'll want to use them together.

        IF NOT EXISTS [condition]

_______________________________________________________________________________

SKIP LAB

    provide a method for bypassing sections of your batchfile.

    For every SKIP command there MUST BE a LAB command!

        /* upper portion of batchfile */
        SKIP name
        /* section to be SKIPped over */
        LAB name
        /* section to be SKIPped to */

    When the DOS reaches the command SKIP, it reads the name that follows
and bypasses the rest of the lines until it reaches a LAB command that has
the same name after it. Then execution continues as normal.

    These are usually, but not necessarily, used in conjunction with
the IF command.

    For example:

        IF [condition]
          SKIP [name]
        ELSE
          [command]
        ENDIF
        /* section that's skipped if the IF condition is true */
        LAB [name]
        /* file continues */

    In this example, if the condition at the IF in the first line isn't met,
the execution will skip down to the line LAB and continue from there.

    One more thing, LAB won't affect the normal flow of the file, if
AmigaDOS runs across one that it hasn't SKIPped to:

    If the condition in the first line IS NOT met and the file ignores the
SKIP command, execution will continue through the commands specified after the
ELSE and right on through the rest of the file paying no attention to the LAB
line. If this is something that you don't desire, use the QUIT command to
terminate, set-up another SKIP, or re-position the LAB keeping in mind that you
can't go backwards.

________________________________________________________________________________

QUIT

    causes a batchfile to exit upon reaching the command

________________________________________________________________________________


    Remember the sample batchfile, we used in the EXECUTE discussion?
Well, it wasn't very polished, so to demonstrate a few of the previous
commands, let's add a few lines to it. Keep in mind that this is just an
example and not meant to perform a real function.

/********** ILLUSTRATION ONLY **************/


.K switch       /* 1st line */
IF "<switch>" EQ "on"
 ASSIGN fonts: DISKNAME:fonts
 COPY DISKNAME:filename ram:
 [RUN] DISKNAME:PROGRAM
 QUIT
ENDIF
IF "<switch>" EQ "off"
 ASSIGN fonts: /* WB:fonts */
 DELETE ram:filename
ENDIF

/*******************************************/

    In a real situation, I'm not sure that it would be worth expanding
this too much more, but...let's throw in a little error checking.
    If the user forgets to type in parameter for "switch", it won't
work. If he types in "On", it won't match. So as a good batchfile writer,
out-think the user, even if it's yourself.
    Mainly, we need a way to inform the user of the usage the file will
expect.

    Here's one way that this can be done:

.K switch       /* 1st line */
IF "<switch>" EQ ""    /* checks for no parameter */
    SKIP usage
ENDIF
IF "<switch>" eq "on"
    ASSIGN fonts: diskname:fonts
    COPY diskname:filename ram:
    [RUN] diskname:program
    QUIT
ENDIF
IF "<switch>" EQ "off"
    IF EXISTS WB:fonts
        ASSIGN fonts: WB:fonts
    ELSE
        ASSIGN fonts:
    ENDIF
    DELETE ram:filename
    QUIT    /* this QUIT is here so that the usage statement won't be
printed if the user typed in the parameter "off" correctly. ENDIF and LAB won't
prevent the normal top->bottom flow, so without the QUIT, execution would
continue past both of those commands and into the usage statement, causing
confusion to the user and prompting him/her to make probably unfounded remarks
about your dubious parentage. In case the user typed in the wrong thing, the
last error we need to consider, control will bypass this IF and print out the
usage statement */
ENDIF
LAB usage
    ECHO "Either use 'on' or 'off' as a parameter"
    /* remember you can't use " inside of the ECHO string, or it
       will think it's found the end */


    OK, so it's not beautiful, but it would work. With the "IF EXISTS"
for the fonts directory, this file could be stored on the disk with the
program and it would check to see if you have a fonts directory on your
WB.


________________________________________________________________________________

   Need more help?

    There are several pages in the AmigaDOS manual that cover EXECUTE
and more on the other commands that have been mentioned. You'd be well
advised to direct your attention to those pages for further study, I've
only scratched the surface.


________________________________________________________________________________

    Now you seen how some of these commands are used, let's build something
that might be considered useful.

    Remember way back when, I said I didn't like the shotgun approach to
putting stuff in ram:c? Now you're going to write a batchfile that will put a
few of the most common commands there instead of copying the whole df0:c (dir).




























    Oh! you'd like a little help? Alright.



    First, we'll need to get ED going, but we'll need to have a name for our
file, I tend to like to give batchfiles a name that both captures the essence of
what it's supposed to do AND is easy to type. "C" might do it, but it could be a
little too succinct. For the sake of the argument, let's use ram_c. Of course
you can use anything you want, but you'll have to do the substitutions:

>> ED s:ram_c

/* The editor starts. Type the following lines in WITHOUT the /* */ comments!!
EXECUTE doesn't recognize that pattern as a comment and you'll be opening
yourself up to a world of hurt! */


    in the ED window

makedir ram:c        /* sets up the destination */
copy c:Copy ram:c
assign c: ram:c        /* this will speed up the process of the repeated use
               of the COPY command */
copy df0:c/Assign c:    /* same source and destination, but different names */
copy df0:c/CD c:
copy df0:c/Dir c:
copy df0:c/Delete c:
copy df0:c/Execute c:
copy df0:c/Path c:
copy df0:c/Run c:

; copy df0:c/ c:
;copy df0:c/ c:        /* the ";" IS the way to do comments in
               a batchfile!! Anything that follows, is ignored.
               Spaces between lines are OK. They make the files
               easier to read.
                 If you leave a line or two like this
               around, should you want to add more, it's a quick
               job of editing. THEY AREN'T REQUIRED!!! I did it
               as an example */
path add c: df0:c    /* PATH looks in current directory and c: right now.
               Since we haven't copied ALL our commands to ram:c,
               we can get it to find the rest this way. So why add
               c: when it's already there? c: is the LAST place that
               gets searched and since all the commands are in df0:c
               too, that's where they'd be found. Like this, they'll
               be found in ram:c first.The other way to go about
               this would be to reASSIGN C: to df0:c and add ram:c
               to the path..like this... */
/* ASSIGN c: df0:c
   PATH ADD ram:c */
;End of File

<ESC>
* x

    So it's saved to the disk, now what?

    This file can be EXECUTEd right now, except that ram:c already exists
and that situation will cause MAKEDIR to fail and the file's execution to end.

    Here's what we'll do..

>> INFO
/* take note of how big ram: is, we'll use this for a comparison */
>> ASSIGN c: df0:c
>> DELETE ram:c all
>> EXECUTE ram_c    /* EXECUTE doesn't NEED to be told it's IN s:, only if
               it's NOT. Remember, it looks there by default. */
>> INFO
/* the size of the ram: disk should be considerably smaller. BTW (by the way)
don't be confused by the fact that you're told there are STILL 0 bytes free in
ram:, no matter how much you have, it always says that. */


    This is all well and good, but now the REAL test of our mettle!
Putting it in the (drum-roll) startup-sequence (a hushed, but lengthy aaaaahhhh)

    We'll be smart, though...lest we make a mistake:

>> COPY s:startup-sequence s:old_startup
/* this gives us a backup in case we mess something up and don't notice! */

Here we go...
>> ED s:startup-sequence
/* here's what you'll find: */

winsize 0 0 600 199
echo "Putting C: in RAM:*nPlease be patient a few minutes..."
makedir ram:C
copy c: ram:c quiet
assign C: ram:C
cls
echo "
[7m THIS WINDOW
[0m will be used by READER to read the instruction text"
echo "and
[7m THE OTHER WINDOW
[0m will be used by you to type COMMANDS into"
echo "to get the feel of the whole thing"
wait 10
newcli "con:0/201/640/199/ Your commands go in this window " s:pmt
cls
echo "
[7m IMPORTANT STUFF....please read!!!
[0m"
echo "*n*n
[3mCLICK in the UPPER window
[0m*n"
echo "At the prompt in the UPPER window,*ntype in this line....*n"
echo "
[33mReader CLI_tutorial.intro
[0m*nThen..."
echo "Use the gadgets at the bottom of the READER to control your position"
echo "within the text. You can change the colors and quit from the READER menu"


    There are already several fatal mistakes in the sequence caused by
merely loading it into ED. Can you find them?

    Look at the ECHO line 7th from the top. There's only:
ECHO "

on it. And the two lines below it are junk! So what happened?
    When I wrote the file, I didn't use ED, I used the MicroEMACS editor
from the EXTRAS disk. EMACS has a way to imbed <ESC> keystrokes in the text,
this allows you to alter the output. Ergo, the text/colors are different in this
case. We'll get into that in the next section, but for now, you'll need to
reconstruct that line.
    ED does allow you to simulate an <ESC> with "*e".
    What you need to do is put an "*e" /* or "*E", it doesn't matter */
IN FRONT of the "[" on all the lines below an ECHO line AND then retype the
ECHO line so that they look like this example:

ECHO "*e[33mReader CLI_tutorial.intro*e[0m*nThen..."

and delete the two lines that start with "[".

Your end result at this point should look like this:

winsize 0 0 640 199
echo "Putting C: in RAM:*nPlease be patient a few minutes..."
makedir ram:C
copy c: ram:c quiet
assign C: ram:C
cls
echo "*e[7m THIS WINDOW *e[0m will be used by READER to read the instruction
     text" /* this HAS to be part of the above line!! */
echo "and *e[7m THE OTHER WINDOW *e[0m will be used by you to type COMMANDS
     into" /* this HAS to be part of the above line!! */
echo "to get the feel of the whole thing"
wait 10
newcli "con:0/201/640/199/ Your commands go in this window " s:pmt
cls
echo "*e[7m IMPORTANT STUFF....please read!!!*e[0m"
echo "*n*n*e[3mCLICK in the UPPER window*e[0m*n"
echo "At the prompt in the UPPER window,*ntype in this line....*n"
echo "*e[33mReader CLI_tutorial.intro*e[0m*nThen..."
echo "Use the gadgets at the bottom of the READER to control your position"
echo "within the text. You can change the colors and quit from the READER menu"

    Great! We're past the hard part. Let's get finished.

    To install our modification, we need to delete the three lines that
begin with "MAKEDIR", "COPY c:", and "ASSIGN", these are the third, fourth, and
fifth lines in the file. The quick way to do this is:

Put the cursor on the line that begins with "MAKEDIR"
Press <CTRL>B and the line will disappear.
Press <CTRL>B twice more.
Move the cursor to the beginning (the left) of the 2d line and press <RETURN>
Move the cursor back up to the empty line we've just created and type:

execute ram_c

    That should do it! Your final file should look like this, with the
exception of the two lines I had to split to fit on the screen here:

winsize 0 0 640 199
echo "Putting C: in RAM:*nPlease be patient a few minutes..."
execute ram_c
cls
echo "*e[7m THIS WINDOW *e[0m will be used by READER to read the instruction
         text" /* this HAS to be part of the above line!! */
echo "and *e[7m THE OTHER WINDOW *e[0m will be used by you to type COMMANDS
         into" /* this HAS to be part of the above line!! */?
echo "to get the feel of the whole thing"
wait 10
newcli "con:0/201/640/199/ Your commands go in this window " s:pmt
cls
echo "*e[7m IMPORTANT STUFF....please read!!!*e[0m"
echo "*n*n*e[3mCLICK in the UPPER window*e[0m*n"
echo "At the prompt in the UPPER window,*ntype in this line....*n"
echo "*e[33mReader CLI_tutorial.intro*e[0m*nThen..."
echo "Use the gadgets at the bottom of the READER to control your position"
echo "within the text. You can change the colors and quit from the READER menu"

    Now:
<ESC>
* x


    Our changes have now been rendered as a series of magnetic hocus-pocus
to the disk. In order to view you handiwork, you'll have to reboot. Don't panic
if it doesn't work, it's probably a simple mistake you can correct by taking
another look at this file. If something does go wrong, make a mental note of
what failed..you'll get a message and that should help you track it down.

    If you need to do more work all you'll need to do is:
>> ED s:startup-sequence
and make whatever changes might be necessary.


    But, since it's going to work, we'll move on to CLI_tutorial.6